Summary

Octopi has always persisted a model-local, dense, contiguous label space
(1, 2, 3, … assigned in argument order by create-targets) into the copick
segmentations it writes (targets, predict). This PR adds an opt-in
alternative in which the segmentations octopi writes hold copick's global
object labels, while the dense [0..K] space that the model needs exists only
transiently inside the training/inference boundary.

The behavior is selected with a new --label-space flag on octopi create-targets:

• --label-space model (default) — unchanged behavior.
• --label-space copick — paint canonical copick global labels on disk; carry a
  {name: model_channel} map plus a label_space: copick marker through the
  targets YAML → model config → segment YAML so every stage can convert between
  the two spaces by object name.

Rationale

In copick, an integer label means the same object everywhere in a project (e.g.
gas-vesicle-shell = 2). Octopi's sequential relabeling breaks that invariant:
a targets/predict segmentation stored by octopi might relabel
gas-vesicle-shell to 1, so the file can only be interpreted if you also carry
octopi's labels map alongside it. Opening such a segmentation with the plain
project config (napari, copick logical/process ops, any downstream consumer)
mislabels every voxel.

--label-space copick fixes this at the source: what octopi writes to disk is
ordinary, canonical copick multilabel. The model still trains and predicts in a
dense [0..K] space (required by the loss, the one-hot encoding, and
RandCropByLabelClassesd), but that space is now a private, derived detail —
compacted from global labels right after loading, and expanded back to global
labels right before writing.

A second benefit: because both conversions are resolved by object name (not
by sort order or by hard-coded integers), a model trained on one project can be
applied to another project whose global labels differ, and the written
predict segmentation will use the target project's globals.

How it works

Two label concepts exist in copick mode:

• paint label — the copick global label, written to disk.
• model channel — the dense [0..K] index the network sees, recorded as the
  labels: {name: channel} map in the YAMLs.

The pipeline converts between them at exactly two boundaries:

• Training (build_compaction_map + MONAI MapLabelValued, inserted right
  after LoadCopickd): global → dense. The map is derived from the recorded
  {name: channel} joined with the project's global labels by name. Objects that
  are painted but not selected as targets fold to background 0.
• Inference (_build_dense_to_global, applied just before the single copick
  write site): dense → global, resolved by name against the target project's
  config. Metrics stay in dense space; only the write boundary expands.

localize reads the label_space marker to decide whether the predict
segmentation already holds globals (copick mode → no value remap) or the model's
dense labels (legacy → remap as before).

Examples

Assume a project with globals membrane = 1, gas-vesicle-shell = 2,
gas-vesicle = 3, and that we train on gas-vesicle-shell and gas-vesicle.

1. Default (--label-space model) — legacy, unchanged.
Targets are painted gas-vesicle-shell → 1, gas-vesicle → 2; the YAML records
labels: {gas-vesicle-shell: 1, gas-vesicle: 2} with no label_space marker.
predict is written in the same dense space. Byte-for-byte identical to before.

2. --label-space copick — the new canonical case.

• targets seg on disk holds globals {0, 2, 3}.
• YAML records labels: {gas-vesicle-shell: 1, gas-vesicle: 2} (dense channels,
  minted by ascending global label) and label_space: copick.
• Training compacts {0, 2, 3} → {0, 1, 2} via orig=[0,1,2,3] → target=[0,0,1,2] (membrane is painted but unselected → 0).
• Inference expands {0, 1, 2} → {0, 2, 3}, so the stored predict seg is
  ordinary copick multilabel and opens correctly under the project config alone.

3. Fine-tuning (--label-space copick --from-model pretrained/model_config.yaml).
Model channels are inherited per object by name from the pretrained config
instead of being minted fresh, so the channel↔object binding is preserved across
the fine-tune. If the pretrained model bound gas-vesicle → channel 5, the new
targets record channel 5 for gas-vesicle. Requesting an object the pretrained
model doesn't define is a hard error (fine-tuning onto a new object set is out of
scope).

4. Cross-project inference.
Train on project A (gas-vesicle = 3), then run octopi segment -c projectB
where gas-vesicle = 7. Because _build_dense_to_global resolves each channel
by name against project B, the written predict seg uses 7. If project B does
not define a predicted object, inference fails loudly rather than writing a
meaningless label.

Backward compatibility

The default path is untouched: without --label-space copick, no marker is
written and every code path behaves exactly as before.

For existing artifacts (targets YAMLs, model configs, and stored
segmentations produced before this change), there is no label_space marker, so:

• get_class_info reports label_space = None;
• build_compaction_map returns (None, None), so get_transforms skips
  MapLabelValued entirely — training is a no-op remap;
• _build_dense_to_global falls back to identity (np.arange) — predictions are
  written in the model's dense space, unchanged;
• localize takes the legacy global→dense remap branch.

The result is bit-identical behavior for all legacy models, targets, and
weights. No data migration is required — existing files keep working via the
identity path, and the new .get('labels') / .get('label_space') guards also
remove a latent KeyError that could occur on label-less configs.

Two consistency checks fail loudly rather than silently mislabeling:

• Multi-config training (MultiCopickDataModule) derives a single shared
  map from the first session, so all configs must assign the same global label to
  each shared object; a disagreement raises ValueError.
• Ensemble inference requires every model in the soup to share the same
  labels and label_space.